home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgramD2.iso / Borland / Borland C++ V5.02 / ADDONINC.PAK / IMSGSYS.H < prev    next >
Encoding:
C/C++ Source or Header  |  1997-05-06  |  10.6 KB  |  266 lines
  1. /*:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  2.  
  3.  imsgsys.h   
  4.  Copyright (c) 1987, 1996 Borland International Inc.  All Rights Reserved.
  5.  $Header:   Y:\admin\bride\addon\deliver\interfac\imsgsys.h_v   1.14   18 Nov 1996 11:29:44   JDOUGLAS  $
  6.  $Revision:   1.14  $
  7.  
  8.  IMessageSystem is used to post messages to the IDE's message window.
  9.    
  10.  Interfaces declared in this file:
  11.  
  12.  implemented by IDE
  13.    IMessageFolder
  14.    IMessageFolder2
  15.    IMessageSystem
  16.  
  17.  implemented by IDE client
  18.    IToolInstance
  19.  
  20.  Overview:
  21.    IMessageSystem is an interface supported by IDE server. Client calls
  22.    IMessageSystem::NewFolder to create a folder.  Client calls 
  23.    IMessageFolder::NewFileMessage() or IMessageFolder::NewMessage() to
  24.    display message in message window. 
  25.    
  26.    Client can also implement IToolInstance. IDE will notify client thru
  27.    IToolInstance::Abort() function when user click cancel button in the
  28.    compile box.  Client tool can abort the tool or do other processing in the
  29.    Abort() function.
  30.    
  31.    New in BCW v5.01:
  32.    A new version of IMessageFolder2 is now available. It adds the ability
  33.    to supply help context info for a message and a mechanism which allows
  34.    the IDE to auto scroll to an add-on error message.
  35.    
  36.    The add-on client can use the QUERY_INTERFACE macro to retrieve an 
  37.    IMessageFolder2 interface from the IMessageFolder pointer returned by 
  38.    IMessageSystem::NewFolder.
  39.    
  40.    An add-on editor can now hook user requests to open a file for editing
  41.    in response to a warning or error message. To take advantage of this, 
  42.    implement your version of IMessageClient, get an IMessageSystem2 pointer 
  43.    (GET_INTERFACE( IMessageSystem2 )) and call its RegisterMessageClient()
  44.    method. See further details under IMessageClient below.
  45.  
  46. :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::*/  
  47. #ifndef __IMSGSYS_H
  48. #define __IMSGSYS_H
  49.  
  50. #include <ideaddon\Imsgsys.uid>
  51. #include <ideaddon\ipolystr.h>
  52. #include <ideaddon\common.h>
  53.  
  54. #define ADDON_MESSAGE_FATAL     0
  55. #define ADDON_MESSAGE_ERROR     1
  56. #define ADDON_MESSAGE_WARNING   2
  57. #define ADDON_MESSAGE_ABORT     3
  58. #define ADDON_MESSAGE_BREAK     4
  59. #define ADDON_MESSAGE_STRING    5
  60. #define ADDON_MESSAGE_INFO      6
  61.  
  62. struct IToolInstance : public IUnknown 
  63. {
  64.   //
  65.   //  Abort() is called by the IDE complile box to abort the tool when
  66.   //  user click the cancel button.
  67.   //      
  68.   //  return 1 if tool is aborted, otherwise 0 is returned
  69.   //
  70.   virtual BOOL BCWADDON_CMETHOD Abort() = 0;
  71. };
  72.  
  73.  
  74. //.............................................................................
  75.  
  76. DECLARE_HANDLE   (HMSGITEM);
  77.  
  78. struct IMessageFolder : IUnknown {
  79.   //
  80.   // NewFileMessage() creates an expandable outline node in message window.
  81.   //
  82.   // IPolyString* pFileName : Specifies the filename to open when user double
  83.   //                          clicks the message displayed in the message window.
  84.   // IPolyString* pMsg      : Specifies the message to be displayed in the
  85.   //                          message window
  86.   //
  87.   // Return:
  88.   //
  89.   //    HMSGITEM a message item handle that can be used as an argument in
  90.   //    NewMessage() call.
  91.   //
  92.   virtual HMSGITEM BCWADDON_CMETHOD NewFileMessage(IPolyString* pFileName, IPolyString* pMsg) = 0;
  93.  
  94.   //
  95.   //  NewMessage() displays a message in the message window. If
  96.   //  NewFileMessage() is called already, 
  97.   //
  98.   //    HMSGITEM      hMsgItem : 
  99.   //                  if hMsgItem is NULL, a  message is displayed at the
  100.   //                  root level.
  101.   //                  if hMsgItem is a valid handle returned by NewFileMessage()
  102.   //                  , the new message is appended as a child node of 
  103.   //                  the node created by NewFileMessage() that returns
  104.   //                  hMsgItem.
  105.   //
  106.   //    IPolyString*  pMsg      : Specifies the message to be displayed.
  107.   //    IPolyString*  pFileName : Specifies the filename to open when user
  108.   //                              double click the message displayed in the
  109.   //                              message window.
  110.   //    unsigned long msgLine   : Specifies the line in pFileName to point the
  111.   //                              the cursor to when the file is opened by
  112.   //                              message window.
  113.   //    short         msgColumn : Specifies the coloum in pFileName to point the
  114.   //                              the cursor to when the file is opened by
  115.   //                              message window.
  116.   //    unsigned      msgType   : Specifies message type. This can be one of the
  117.   //                              ADDON_MESSAGE_* listed in this file.
  118.   //
  119.   //
  120.   virtual void BCWADDON_CMETHOD NewMessage(  
  121.                      HMSGITEM hMsgItem,
  122.                      IPolyString*  pMsg,
  123.                      IPolyString*  pFileName = 0,
  124.                      unsigned long msgLine = 0,
  125.                      short         msgColumn = 0,
  126.                      unsigned      msgType = ADDON_MESSAGE_STRING) = 0;
  127.  
  128.   //
  129.   // EnableTransferUI() allows client to notify IDE to call
  130.   // IToolInstance::Abort() when the cancel button is clicked in the compile
  131.   // box.
  132.   //
  133.   virtual  void BCWADDON_CMETHOD EnableTransferUI(IToolInstance* pTool) = 0;
  134.   
  135. };
  136.  
  137.  
  138. struct IMessageFolder2 : public IMessageFolder {
  139.   //
  140.   //  Create a new message. In addition to the args described above for
  141.   //  IMessageFolder::NewMessage, this adds a help filename and context id.
  142.   //
  143.   virtual void BCWADDON_CMETHOD NewMessage2(  HMSGITEM      hMsgItem,
  144.                                 IPolyString*  pMsg,
  145.                                 IPolyString*  pFileName = 0,
  146.                                 unsigned long msgLine = 0,
  147.                                 short         msgColumn = 0,
  148.                                 unsigned      msgType = ADDON_MESSAGE_STRING,
  149.                                 unsigned long helpContextID = 0,
  150.                                 IPolyString*  pHelpfileName = 0) = 0;
  151.  
  152.   //
  153.   // Notify message system that a series of messages are about to be
  154.   // generated. This will allow the IDE to scroll the message window
  155.   // to a fatal, error or warning message in the group.
  156.   // Note: Only messages created after this call will be part of the 
  157.   // group. 
  158.   //
  159.   virtual void BCWADDON_CMETHOD BeginAutoScrollGroup()=0;
  160.  
  161.   //
  162.   // Notify message system that a message generating "session" is ending
  163.   //
  164.   virtual void BCWADDON_CMETHOD EndAutoScrollGroup()=0;
  165.  
  166. };
  167.  
  168.  
  169.  
  170. struct IMessageSystem : public IUnknown {
  171.   // 
  172.   // Create a message folder in message system.  This does not cause anything
  173.   // to be displayed.
  174.   //
  175.   // IPolyString* name : Specifies the name of the tool, please use "Addon" for 
  176.   // this (this will cause the Addon glyph to appear next to your messages).
  177.   // 
  178.   // IPolyString* pTab : Specifies the message window tab to display the message.
  179.   // 
  180.   // 
  181.   virtual IMessageFolder* BCWADDON_CMETHOD NewFolder(IPolyString* name
  182.                                   , IPolyString* pTab = 0) = 0;
  183. };
  184.  
  185.  
  186. struct IMessageClient : public IUnknown {
  187.    //
  188.    // IMessageClient is used to hook user requests to view or edit a file
  189.    // in response to an error or warning message. 
  190.    // 
  191.    // 1) Implement a class derived from IMessageClient.
  192.    // 2) Register your IMessageClient pointer through 
  193.    // IMessageSystem2::RegisterMessageClient(), preferably at startup time. If
  194.    // you register any time after the first message appears in the message
  195.    // window, you may have lost your opportunity to handle messages.
  196.    // 
  197.    // Note: If more than one add-on tries to handle the same types of messages,
  198.    // only one will prevail - the others won't ever receive the 
  199.    // CanHandleMessage() call. Which add-on gets first crack at this is 
  200.    // a matter of who registers first and can ultimately be dependant on 
  201.    // which addon appears in the registry first. There is no way to guarantee
  202.    // that your add-on will or won't be first and the order that you are called
  203.    // is clearly undefined behavior. End users should be encouraged to install
  204.    // only one third-party editor.
  205.    // 
  206.    
  207.    // 
  208.    // CanHandleMessage() will be called once for each unique type of message
  209.    // handling request. Unique, in this case, means that it is the first
  210.    // message request that has a particular 'handlerType' combined with a
  211.    // particular 'action'.
  212.    // 
  213.    // Editors will want to handle messages with handler type "SourceEditor"
  214.    // and possibly those with handler type "ToolClientNFM" and should 
  215.    // return FALSE to any other CanHandleMessage() requests.
  216.    // 
  217.    // If the handler type is "SourceEditor", the file referred to by the 
  218.    // message is a text file. However, messages with "ToolClientNFM" as the
  219.    // designated handler are generated as "top level" messages by the project 
  220.    // manager for everything it builds, makes or invokes. You may want to 
  221.    // support viewing or editing the files associated with some of these 
  222.    // messages, based on the file extension. 
  223.    // 
  224.    // There are currenly three 'action' strings that a SourceEditor should 
  225.    // handle:
  226.    //    "Edit" - open the file at the specified location for editing
  227.    //    "View" - open the file at the specified location for viewing
  228.    //    "Show" - If the file is already open in a buffer, position to the
  229.    //             specified location. 
  230.    //    
  231.    // Note that Show requests come through in response to message window 
  232.    // scrolling to match the currently selected message, while Edit and View
  233.    // requests come about as a result of a user <ENTER>, double-click or
  234.    // speed-menu action on a particular message.
  235.    // 
  236.    // Please see the testbed example msgcli.h and msgcli.cpp for an example
  237.    // of simple implementation - you can also use the testbed example to spy
  238.    // on the CanHandleMessage() and HandleMessage() callbacks. We also 
  239.    // recommend taking a close look at how the BCW editor reacts to message 
  240.    // handling requests.
  241.    //
  242.    virtual BOOL BCWADDON_CMETHOD CanHandleMessage( 
  243.          IPolyString * handlerType, 
  244.          IPolyString * action ) = 0;
  245.    
  246.    //
  247.    // HandleMessage() will be called for all message request types that you 
  248.    // responded TRUE to in CanHandleMessage(). 
  249.    //
  250.    virtual void BCWADDON_CMETHOD HandleMessage( 
  251.          IPolyString * action,
  252.          int column,
  253.          int line,
  254.          IPolyString * filePath ) = 0;
  255. };
  256.  
  257.  
  258. struct IMessageSystem2 : public IMessageSystem {
  259.    virtual void BCWADDON_CMETHOD RegisterMessageClient( 
  260.          IMessageClient * client ) = 0;
  261. };
  262.  
  263.  
  264.  
  265. #endif // __IMSGSYS_H
  266.